IRIX Base Documentation 2002 November

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / c++ / sbuf.prot.z / sbuf.prot

Wrap

Text File | 2002-10-03 | 22.5 KB | 358 lines

SBUF.PROT(3C) Last changed: 10-20-98 NNAAMMEE ssttrreeaammbbuuff - Interface for derived classes SSYYNNOOPPSSIISS ##iinncclluuddee <<iioossttrreeaamm..hh>> ttyyppeeddeeff lloonngg ssttrreeaammooffff,, ssttrreeaammppooss;; ccllaassss iiooss {{ ppuubblliicc:: eennuumm sseeeekk__ddiirr {{ bbeegg,, ccuurr,, eenndd }};; eennuumm ooppeenn__mmooddee {{ iinn,, oouutt,, aattee,, aapppp,, ttrruunncc,, nnooccrreeaattee,, nnoorreeppllaaccee }} ;; //// aanndd lloottss ooff ootthheerr ssttuuffff,, sseeee iiooss((33CC)) ...... }} ;; ccllaassss ssttrreeaammbbuuff {{ ppuubblliicc:: ssttrreeaammbbuuff(()) ;; ssttrreeaammbbuuff((cchhaarr** pp,, iinntt lleenn));; vvooiidd ddbbpp(()) ;; pprrootteecctteedd:: iinntt aallllooccaattee(());; cchhaarr** bbaassee(());; iinntt bblleenn(());; cchhaarr** eebbaacckk(());; cchhaarr** eebbuuff(());; cchhaarr** eeggppttrr(());; cchhaarr** eeppppttrr(());; vvooiidd ggbbuummpp((iinntt nn));; cchhaarr** ggppttrr(());; cchhaarr** ppbbaassee(());; vvooiidd ppbbuummpp((iinntt nn));; cchhaarr** ppppttrr(());; vvooiidd sseettgg((cchhaarr** eebb,, cchhaarr** gg,, cchhaarr** eegg));; vvooiidd sseettpp((cchhaarr** pp,, cchhaarr** eepp));; vvooiidd sseettbb((cchhaarr** bb,, cchhaarr** eebb,, iinntt aa==00));; iinntt uunnbbuuffffeerreedd(());; vvooiidd uunnbbuuffffeerreedd((iinntt));; vviirrttuuaall iinntt ddooaallllooccaattee(());; vviirrttuuaall ~~ssttrreeaammbbuuff(()) ;; ppuubblliicc:: vviirrttuuaall iinntt ppbbaacckkffaaiill((iinntt cc));; vviirrttuuaall iinntt oovveerrffllooww((iinntt cc==EEOOFF));; vviirrttuuaall iinntt uunnddeerrffllooww(());; vviirrttuuaall ssttrreeaammbbuuff** sseettbbuuff((cchhaarr** pp,, iinntt lleenn));; vviirrttuuaall ssttrreeaammppooss sseeeekkppooss((ssttrreeaammppooss,, iinntt ==iiooss::::iinn||iiooss::oouutt));; vviirrttuuaall ssttrreeaammppooss sseeeekkooffff((ssttrreeaammooffff,, sseeeekk__ddiirr,, iinntt ==iiooss::::iinn||iiooss::oouutt));; vviirrttuuaall iinntt ssyynncc(());; }};; IIMMPPLLEEMMEENNTTAATTIIOONN IRIX systems DDEESSCCRRIIPPTTIIOONN A ssttrreeaammbbuuff implements the buffer abstraction described in ssbbuuff..ppuubb(3C). However, the ssttrreeaammbbuuff class itself contains only basic members for manipulating the characters and, usually a class derived from ssttrreeaammbbuuff will be used. This man page describes the interface needed by programmers who are coding a derived class. Two kinds of member functions are described. The nonvirtual functions are provided for manipulating a ssttrreeaammbbuuff in ways that are appropriate in a derived class. Their descriptions reveal details of the implementation that would be inappropriate in the public interface. The virtual functions permit the derived class to specialize the ssttrreeaammbbuuff class in ways appropriate to the specific sources and sinks that it is implementing. The descriptions of the virtual functions explain the obligations of the virtuals of the derived class. If the virtuals behave as specified, the ssttrreeaammbbuuff will perform as specified in the public interface. However, if the virtuals do not perform as specified, then the ssttrreeaammbbuuff may not perform properly, and an iioossttrreeaamm (or any other code) that relies on proper behavior of the ssttrreeaammbbuuff may not perform properly either. In the following descriptions, the following assumptions are made: * _s_b is a ssttrreeaammbbuuff**. * _i and _n are iinntts. * _p_t_r, _b, _e_b, _p, _e_p, _e_b, _g, and _e_g are cchhaarr**s. * - _c is an iinntt character (positive or EEOOFF)). * _p_o_s is a ssttrreeaammppooss. (See ssbbuuff..ppuubb(3C).) * _o_f_f is a ssttrreeaammooffff. * _d_i_r is a sseeeekkddiirr. * _m_o_d_e is an iinntt representing an ooppeenn__mmooddee. CCoonnssttrruuccttoorrss ssttrreeaammbbuuff(()) Constructs an empty buffer corresponding to an empty sequence. ssttrreeaammbbuuff((_b,,_l_e_n)) Constructs an empty buffer and then sets up the reserve area to be the _l_e_n bytes starting at _b. TThhee GGeett,, PPuutt,, aanndd RReesseerrvveerr AArreeaa The protected members of ssttrreeaammbbuuff present an interface to derived classes organized around three areas (arrays of bytes) managed cooperatively by the base and derived classes. They are the _g_e_t _a_r_e_a, the _p_u_t _a_r_e_a, and the _r_e_s_e_r_v_e _a_r_e_a (or buffer). The get and the put areas are normally disjoint, but they may both overlap the reserve area, whose primary purpose is to be a resource in which space for the put and get areas can be allocated. The get and the put areas are changed as characters are put into and gotten from the buffer, but the reserve area normally remains fixed. The areas are defined by a collection of cchhaarr** values. The buffer abstraction is described in terms of pointers that point between characters, but the cchhaarr** values must point at cchhaarrs. To establish a correspondence, the cchhaarr** values should be thought of as pointing just before the byte they really point at. FFuunnccttiioonnss ttoo EExxaammiinnee tthhee PPooiinntteerrss _p_t_r==_s_b-->>bbaassee(()) Returns a pointer to the first byte of the reserve area. The reserve area is the space between _s_b-->>bbaassee(()) _a_n_d _s_b-->>eebbuuff(()). _p_t_r==_s_b-->>eebbaacckk(()) Returns a pointer to a lower bound on _s_b-->>ggppttrr(()). _T_h_e _s_p_a_c_e _b_e_t_w_e_e_n _s_b-->>eebbaacckk(()) _a_n_d _s_b-->>ggppttrr(()) _i_s _a_v_a_i_l_a_b_l_e _f_o_r _p_u_t_b_a_c_k. _p_t_r==_s_b-->>eebbuuff(()) Returns a pointer to the byte after the last byte of the reserve area. _p_t_r==_s_b-->>eeggppttrr(()) Returns a pointer to the byte after the last byte of the get area. _p_t_r==_s_b-->>eeppppttrr(()) Returns a pointer to the byte after the last byte of the put area. _p_t_r==_s_b-->>ggppttrr(()) Returns a pointer to the first byte of the get area. The available characters are those between _s_b-->>ggppttrr(()) _a_n_d _s_b-->>eeggppttrr(()). _T_h_e _n_e_x_t _c_h_a_r_a_c_t_e_r _f_e_t_c_h_e_d _w_i_l_l _b_e **_s_b-->>ggppttrr(()))) _u_n_l_e_s_s _s_b-->>eeggppttrr(()) _i_s _l_e_s_s _t_h_a_n _o_r _e_q_u_a_l _t_o _s_b-->>ggppttrr(()). _p_t_r==_s_b-->>ppbbaassee(()) Returns a pointer to the put area base. Characters between _s_b-->>ppbbaassee(()) _a_n_d _s_b-->>ppppttrr(()) _h_a_v_e _b_e_e_n _s_t_o_r_e_d _i_n_t_o _t_h_e _b_u_f_f_e_r _a_n_d _n_o_t _y_e_t _c_o_n_s_u_m_e_d. _p_t_r==_s_b-->>ppppttrr(()) Returns a pointer to the first byte of the put area. The space between ssbb-->>ppppttrr(()) aanndd ssbb-->>eeppppttrr(()) iiss tthhee ppuutt aarreeaa.. TThhiiss iiss wwhheerree cchhaarraacctteerrss wwiillll bbee ssttoorreedd.. FFuunnccttiioonnss ffoorr SSeettttiinngg tthhee PPooiinntteerrss Note that to indicate that a particular area (get, put, or reserve) does not exist, all the associated pointers should be set to zero. _s_b-->>sseettbb((_b,, _e_b,, _i)) Sets bbaassee(()) and eebbuuff(()) to _b and _e_b respectively. _i controls whether the area will be subject to automatic deletion. If _i is non-zero, then _b will be deleted when bbaassee is changed by another call of sseettbb(()), or when the destructor is called for **_s_b.. IIff _b aanndd _e_b aarree bbootthh nnuullll tthheenn wwee ssaayy tthhaatt tthheerree iiss nnoo rreesseerrvvee aarreeaa.. IIff _b iiss nnoonn--nnuullll,, tthheerree iiss aa rreesseerrvvee aarreeaa eevveenn iiff _e_b iiss lleessss tthhaann _b aanndd ssoo tthhee rreesseerrvvee aarreeaa hhaass zzeerroo lleennggtthh.. _s_b-->>sseettpp((_p,, _e_p)) Sets ppppttrr(()) to _p, ppbbaassee(()) to _p, and eeppppttrr(()) to _e_p. _s_b-->>sseettgg((_e_b,, _g,, _e_g)) Sets eebbaacckk(()) to _e_b, ggppttrr(()) to _g, and eeggppttrr(()) to _e_g. OOtthheerr NNoonn--vviirrttuuaall MMeemmbbeerrss _i==_s_b-->>aallllooccaattee(()) Tries to set up a reserve area. If a reserve area already exists or if _s_b-->>uunnbbuuffffeerreedd(()) _i_s _n_o_n_z_e_r_o, aallllooccaattee(()) _r_e_t_u_r_n_s _0 _w_i_t_h_o_u_t _d_o_i_n_g _a_n_y_t_h_i_n_g. _I_f _t_h_e _a_t_t_e_m_p_t _t_o _a_l_l_o_c_a_t_e _s_p_a_c_e _f_a_i_l_s, aallllooccaattee(()) _r_e_t_u_r_n_s EEOOFF, _o_t_h_e_r_w_i_s_e (_a_l_l_o_c_a_t_i_o_n _s_u_c_c_e_e_d_s) aallllooccaattee(()) _r_e_t_u_r_n_s _1. aallllooccaattee(()) _i_s _n_o_t _c_a_l_l_e_d _b_y _a_n_y _n_o_n- _v_i_r_t_u_a_l _m_e_m_b_e_r _f_u_n_c_t_i_o_n _o_f ssttrreeaammbbuuff. _i==_s_b-->>bblleenn(()) Returns the size (in cchhaarrs) of the current reserve area. ddbbpp(()) Writes directly on file descriptor 1 information in ASCII about the state of the buffer. It is intended for debugging and nothing is specified about the form of the output. It is considered part of the protected interface because the information it prints can only be understood in relation to that interface, but it is a public function so that it can be called anywhere during debugging. _s_b-->>ggbbuummpp((_n)) Increments ggppttrr(()) by _n which may be positive or negative. No checks are made on whether the new value of ggppttrr(()) is in bounds. _s_b-->>ppbbuummpp((_n)) Increments ppppttrr(()) by _n which may be positive or negative. No checks are made on whether the new value of ppppttrr(()) is in bounds. _s_b-->>uunnbbuuffffeerreedd((ii)) _i==_s_b-->>uunnbbuuffffeerreedd(()) There is a private variable known as _s_b's buffering state. _s_b-- >>uunnbbuuffffeerreedd((_i)) _s_e_t_s _t_h_e _v_a_l_u_e _o_f _t_h_i_s _v_a_r_i_a_b_l_e _t_o _i _a_n_d _s_b-- >>uunnbbuuffffeerreedd(()) _r_e_t_u_r_n_s _t_h_e _c_u_r_r_e_n_t _v_a_l_u_e. _T_h_i_s _s_t_a_t_e _i_s _i_n_d_e_p_e_n_d_e_n_t _o_f _t_h_e _a_c_t_u_a_l _a_l_l_o_c_a_t_i_o_n _o_f _a _r_e_s_e_r_v_e _a_r_e_a. _I_t_s _p_r_i_m_a_r_y _p_u_r_p_o_s_e _i_s _t_o _c_o_n_t_r_o_l _w_h_e_t_h_e_r _a _r_e_s_e_r_v_e _a_r_e_a _i_s _a_l_l_o_c_a_t_e_d _a_u_t_o_m_a_t_i_c_a_l_l_y _b_y aallllooccaattee. VViirrttuuaall MMeemmbbeerr FFuunnccttiioonnss Virtual functions may be redefined in derived classes to specialize the behavior of ssttrreeaammbbuuffs. This section describes the behavior that these virtual functions should have in any derived classes; the next section describes the behavior that these functions are defined to have in base class ssttrreeaammbbuuff. _i==_s_b-->>ddooaallllooccaattee(()) Is called when aallllooccaattee(()) determines that space is needed. ddooaallllooccaattee(()) is required to call sseettbb(()) to provide a reserve area or to return EEOOFF if it cannot. It is only called if _s_b-->>uunnbbuuffffeerreedd(()) _i_s _z_e_r_o _a_n_d _s_b-->>bbaassee(()) _i_s _z_e_r_o. _i==oovveerrffllooww((_c)) Is called to consume characters. If _c is not EEOOFF, oovveerrffllooww(()) also must either save _c or consume it. Usually it is called when the put area is full and an attempt is being made to store a new character, but it can be called at other times. The normal action is to consume the characters between ppbbaassee(()) and ppppttrr(()), call sseettpp(()) to establish a new put area, and if _c!!==EEOOFF _s_t_o_r_e _i_t (_u_s_i_n_g ssppuuttcc(())). _s_b-->>oovveerrffllooww(()) _s_h_o_u_l_d _r_e_t_u_r_n EEOOFF _t_o _i_n_d_i_c_a_t_e _a_n _e_r_r_o_r; _o_t_h_e_r_w_i_s_e _i_t _s_h_o_u_l_d _r_e_t_u_r_n _s_o_m_e_t_h_i_n_g _e_l_s_e. _i==_s_b-->>ppbbaacckkffaaiill((_c)) Is called when eebbaacckk(()) equals ggppttrr(()) and an attempt has been made to putback _c. If this situation can be dealt with (e.g., by repositioning an external file), ppbbaacckkffaaiill(()) should return _c; otherwise it should return EEOOFF. _p_o_s==_s_b-->>sseeeekkooffff((_o_f_f,, _d_i_r,, _m_o_d_e)) Repositions the get and/or put pointers (i.e., the abstract get and put pointers, not ppppttrr(()) and ggppttrr(())). The meanings of _o_f_f and _d_i_r are discussed in ssbbuuff..ppuubb(3C). _m_o_d_e specifies whether the put pointer (iiooss::::oouutt bit set) or the get pointer (iiooss::::iinn bit set) is to be modified. Both bits may be set in which case both pointers should be affected. A class derived from ssttrreeaammbbuuff is not required to support repositioning. sseeeekkooffff(()) should return EEOOFF if the class does not support repositioning. If the class does support repositioning, sseeeekkooffff(()) should return the new position or EEOOFF on error. _p_o_s==_s_b-->>sseeeekkppooss((_p_o_s,, _m_o_d_e)) Repositions the ssttrreeaammbbuuff get and/or put pointer to _p_o_s. _m_o_d_e specifies which pointers are affected as for sseeeekkooffff(()). Returns _p_o_s (the argument) or EEOOFF if the class does not support repositioning or an error occurs. _s_b==_s_b-->>sseettbbuuff((_p_t_r,, _l_e_n)) Offers the array at _p_t_r with _l_e_n bytes to be used as a reserve area. The normal interpretation is that if _p_t_r or _l_e_n are zero then this is a request to make the _s_b unbuffered. The derived class may use this area or not as it chooses. It may accept or ignore the request for unbuffered state as it chooses. sseettbbuuff(()) should return _s_b if it honors the request. Otherwise it should return 0. ii==_s_b-->>ssyynncc(()) Is called to give the derived class a chance to look at the state of the areas, and synchronize them with any external representation. Normally ssyynncc(()) should consume any characters that have been stored into the put area, and if possible give back to the source any characters in the get area that have not been fetched. When ssyynncc(()) returns there should not be any unconsumed characters, and the get area should be empty. ssyynncc(()) should return EEOOFF if some kind of failure occurs. _i==_s_b-->>uunnddeerrffllooww(()) Is called to supply characters for fetching, i.e., to create a condition in which the get area is not empty. If it is called when there are characters in the get area it should return the first character. If the get area is empty, it should create a nonempty get area and return the next character (which it should also leave in the get area). If there are no more characters available, uunnddeerrffllooww(()) should return EEOOFF and leave an empty get area. The default definitions of the virtual functions: _i==_s_b-->>ssttrreeaammbbuuff::::ddooaallllooccaattee(()) Attempts to allocate a reserve area using ooppeerraattoorr nneeww. _i==_s_b-->>ssttrreeaammbbuuff::::oovveerrffllooww((_c)) Is compatible with the old stream package, but that behavior is not considered part of the specification of the iostream package. Therefore, ssttrreeaammbbuuff::::oovveerrffllooww(()) should be treated as if it had undefined behavior. That is, derived classes should always define it. _i==_s_b-->>ssttrreeaammbbuuff::::ppbbaacckkffaaiill((_c)) Returns EEOOFF. _p_o_s==_s_b-->>ssttrreeaammbbuuff::::sseeeekkppooss((_p_o_s,, _m_o_d_e)) Returns _s_b-->>sseeeekkooffff((ssttrreeaammooffff((_p_o_s)),,iiooss::::bbeegg,,_m_o_d_e)). _T_h_u_s _t_o _d_e_f_i_n_e _s_e_e_k_i_n_g _i_n _a _d_e_r_i_v_e_d _c_l_a_s_s, _i_t _i_s _f_r_e_q_u_e_n_t_l_y _o_n_l_y _n_e_c_e_s_s_a_r_y _t_o _d_e_f_i_n_e sseeeekkooffff(()) _a_n_d _u_s_e _t_h_e _i_n_h_e_r_i_t_e_d ssttrreeaammbbuuff::::sseeeekkppooss(()). _p_o_s==_s_b-->>ssttrreeaammbbuuff::::sseeeekkooffff((_o_f_f,, _d_i_r,, _m_o_d_e)) Returns EEOOFF. _s_b==_s_b-->>ssttrreeaammbbuuff::::sseettbbuuff((_p_t_r,, _l_e_n)) Will honor the request when there is no reserve area. _i==_s_b-->>ssttrreeaammbbuuff::::ssyynncc(()) Returns 0 if the get area is empty and there are no unconsumed characters. Otherwise it returns EEOOFF. ii==_s_b-->>ssttrreeaammbbuuff::::uunnddeerrffllooww(()) Is compatible with the old stream package, but that behavior is not considered part of the specification of the iostream package. Therefore, ssttrreeaammbbuuff::::uunnddeerrffllooww(()) should be treated as if it had undefined behavior. That is, it should always be defined in derived classes. CCAAVVEEAATTSS The constructors are public for compatibility with the old stream package. They should be protected. The interface for unbuffered actions is awkward. It is difficult to write uunnddeerrffllooww(()) and oovveerrffllooww(()) virtuals that behave properly for unbuffered ssttrreeaammbbuuff(())s without special casing. Also there is no way for the virtuals to react properly to multi-character gets or puts. Although the public interface to ssttrreeaammbbuuffs deals in characters and bytes, the interface to derived classes deals in cchhaarrs. Since a decision had to be made on the types of the real data pointers, it seemed easier to reflect that choice in the types of the protected members than to duplicate all the members with both plain and unsigned char versions. But perhaps all these uses of cchhaarr** ought to have been with a typedef. The implementation contains a variant of sseettbbuuff(()) that accepts a third argument. It is present only for compatibility with the old stream package. SSEEEE AALLSSOO ssbbuuff..ppuubb(3C), ssttrreeaammbbuuff(3C), iiooss(3C), iissttrreeaamm(3C), oossttrreeaamm(3C) This man page is available only online.